Defining Different Paper Sizes(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 4 - Advanced Printing Features / Using Advanced Printing Features

Defining Different Paper Sizes
QuickDraw GX allows you to define unique paper types for the individual pages of a printable document. You can use the GXNewPaperType function to create a new paper-type object for the specified job object, or you can use the GXGetNewPaperType function to load a paper-type object from a resource. You use the GXGetJobPaperType function to obtain a specific paper-type object by its index into the total set of paper-type object definitions that are accessible from a specific job object. You can use the GXCountJobPaperTypes to obtain the total number of paper-type object definitions that are accessible to a particular job object.

Creating a Paper-Type Object
Listing 4-10 shows how to create a new paper-type object. When you create a paper-type object, you specify its name and rectangles that define the paper type's page size and paper size.
Listing 4-10 Creating a new paper-type object
OSErr MyCreatePaperType(MyDocumentPtr myDocument, Str31 paperName, 
                     gxRectangle *pageSize,gxRectangle *paperSize, 
                     gxPaperType *newPaperType)
{
   *newPaperType = GXNewPaperType(myDocument->documentJob,
                                 paperName, pageSize, paperSize);

   return GXGetJobError(myDocument->documentJob);
}
You use the GXDisposePaperType function to dispose of a paper-type object when it is no longer needed.

Obtaining the Name of a Paper Type
You use the GXGetPaperTypeName function to obtain a paper-type object's name. Listing 4-11 shows how to use this function to obtain the name of a paper-type object associated with a format object.
Listing 4-11 Obtaining a paper-type object's name
OSErr MyGetPaperTypeName(MyDocumentPtr myDocument, Str255 
                           paperTypeName)
{
   gxPaperType thePaperType;
   long        curPage;
   gxFormat    pgFormat;

   /* 
      Get the format object for the current page. If it is nil,
      you should use the default format.
   */
   curPage = myDocument->curPage;
   pgFormat = myDocument->pageFormat[curPage -1];
   if (pgFormat == nil)
      pgFormat = GXGetJobFormat(myDocument->documentJob, 1);

   /* Get the format object's paper-type and name. */
   thePaperType = GXGetFormatPaperType(pgFormat);
   GXGetPaperTypeName(thePaperType, paperTypeName);

   return GXGetJobError(myDocument->documentJob);
}
Obtaining the Dimensions of a Paper Type
You use the GXGetPaperTypeDimensions function to obtain the page rectangle and the paper rectangle associated with a paper-type object. The page rectangle is the imageable portion of a page. The paper rectangle defines the size of a page. The rectangle size is specified in fixed 72 dpi units. Listing 4-12 shows how to use this function.
Listing 4-12 Obtaining page and paper rectangles for a paper-type object
OSErr MyGetPaperTypeDimensions(MyDocumentPtr myDocument,
                              gxRectangle *pageBounds, 
                              gxRectangle *paperBounds)
{
   gxPaperType    thePaperType;
   long           curPage;
   gxFormat       pgFormat;

/*
   Get the format object for the current page. If it is nil, use 
   the job object's default format.
*/
   curPage = myDocument->curPage;
   pgFormat = myDocument->pageFormat[curPage -1];
   if (pgFormat == nil)
      pgFormat = GXGetJobFormat(myDocument->documentJob, 1);

   /* 
      Get the format's paper type and the paper type's bounds.
      Note that you can also use GXGetFormatDimensions to do this.
   */
   thePaperType = GXGetFormatPaperType(pgFormat);
   GXGetPaperTypeDimensions(thePaperType, pageBounds,
                                          paperBounds);

   return GXGetJobError(myDocument->documentJob);
}
Scanning the Paper Types Available to a Job
You use the GXForEachJobPaperTypeDo function to call an application-defined function for each paper-type object that is accessible to a particular job. The parameters for the GXForEachJobPaperTypeDo function, in order, are:

the job object whose paper-type objects you wish to examine or change
a pointer to the application-defined function you want to execute on these paper-type objects
a pointer to a reference constant that refers to additional data you want to make available to the application-defined function
a Boolean value that specifies whether you wish to include paper-type objects associated with the formatting printer (true) or those associated with the output printer (false)

Listing 4-13 shows you how to call an application-defined function, MyPaperTypeFunction, for each paper-type object associated with the print job's output printer. The pointer to the reference constant is nil.
Listing 4-13 Executing a function for each paper-type object
OSErr MyListAllPaperTypes(MyDocumentPtr myDocument)
{
   GXForEachJobPaperTypeDo(myDocument->documentJob, 
                     (gxPaperTypeProc) MyPaperTypeFunction, nil, 
                     false);
   return GXGetJobError(myDocument->documentJob);
}
An application-defined function executed by the GXForEachJobPaperTypeDo function is defined as follows:
typedef gxLoopStatus (*gxPaperTypeProc) (gxPaperType aPaperType,
                                          void *refCon);
The first parameter to the application-defined function is the paper-type object that is to be processed. It is set by the GXForEachJobPaperTypeDo function to the next paper-type object automatically. The second parameter is the reference constant passed in by the call to GXForEachJobPaperTypeDo. The application-defined function returns a loop status, which it may set to terminate the GXForEachJobPaperTypeDo function before every paper-type object has been processed.
Listing 4-14 shows an example of an application-defined function that retrieves the paper type's name and dimensions and can be used to display them. It always returns gxKeepLooping, which prevents the GXForEachJobPaperTypeDo function from terminating until each paper-type object has been processed.
Listing 4-14 Executing a procedure for each paper-type object
pascal gxLoopStatus MyPaperTypeFunction(gxPaperType thePaperType,
                                       void *refCon)
{
   gxRectangle pageBounds, paperBounds;
   Str255      paperTypeName;

   /* Get the paper-type object's name. */
   GXGetPaperTypeName(thePaperType, paperTypeName);

   /* Add code here to display the paper-type object's name. */
   ...

   /* Get the paper-type object's dimensions. */
   GXGetPaperTypeDimensions(thePaperType, &pageBounds, 
                           &paperBounds);

   /* Add code here to display the dimensions. */
   ...

   /* Keep looping until all paper types are accessed. */
   return gxKeepLooping;
}